Skip to content

feat: reserve "key" field in page configuration for stable slide referencing#527

Draft
k1LoW wants to merge 2 commits into
mainfrom
key
Draft

feat: reserve "key" field in page configuration for stable slide referencing#527
k1LoW wants to merge 2 commits into
mainfrom
key

Conversation

@k1LoW
Copy link
Copy Markdown
Owner

@k1LoW k1LoW commented May 27, 2026

Refs: #523

This pull request reserves key as a well-known optional field in the per-page JSON configuration comment, so that AI agents and external tooling can refer to a specific slide by a stable, opaque identifier instead of relying on page numbers, headings, or body fragments — all of which shift or collide in practice.

Behavior:

  • key is optional and opaque; deck does not interpret its content, length, or character set.
  • It has no effect on rendering and is not considered for content equality (changing only the key does not trigger a slide update).
  • Empty values are treated as unset.
  • Uniqueness is enforced at parse time. Two pages declaring the same non-empty key cause Parse to return duplicate page key %q at pages %d and %d, so downstream consumers can rely on the identity guarantee rather than treating it as a convention.

Example:

<!-- {"key": "a7b5", "layout": "title-and-body"} -->

# Slide title

---

<!-- {"key": "c9d2"} -->

# Another slide

Changes:

  • Add Key field to md.Config and md.Content, and copy it through when parsing the page-config HTML comment.
  • Add validateKeys and call it from md.Parse after defaults are reflected.
  • Update README.md (page configuration section and the agent-facing guide) to document key.
  • Add testdata/key.md (+ golden) to TestParse and a new TestValidateKeys covering: no keys, all unique, mixed keyed/unkeyed, empty-key collisions (not duplicates), and a duplicate-key error.

Verified with go build ./... and go test ./... (all packages pass).

…rencing

When editing a deck with an AI agent or external tooling, there has been
no stable way to refer to a specific slide across turns: deictic references
("this slide") don't survive turns, page numbers shift on every insert or
delete, and titles or body fragments are rarely unique.

Reserve "key" as a well-known optional field in the per-page JSON config
to give downstream tooling a stable, opaque identifier for each slide.

- Optional, opaque string with no rendering effect (treated similarly to
  "freeze" / "skip" / "ignore" in that it never appears in the rendered
  output).
- Empty values are treated as unset.
- Uniqueness is enforced at parse time so that consumers can rely on the
  identity guarantee instead of treating it as convention.

Refs: #523
@k1LoW k1LoW self-assigned this May 29, 2026
@k1LoW k1LoW added enhancement New feature or request tagpr:minor labels May 29, 2026
golangci-lint funcorder requires unexported methods to come after the
struct's exported methods. The unexported validateKeys sat between Parse
and ToSlides, which tripped the linter on CI.
@github-actions
Copy link
Copy Markdown
Contributor

Code Metrics Report

main (f9697fd) #527 (8c8526d) +/-
Coverage 33.7% 33.9% +0.2%
Code to Test Ratio 1:0.9 1:0.9 +0.0
Test Execution Time 12s 14s +2s
Details
  |                     | main (f9697fd) | #527 (8c8526d) |  +/-  |
  |---------------------|----------------|----------------|-------|
+ | Coverage            |          33.7% |          33.9% | +0.2% |
  |   Files             |             31 |             31 |     0 |
  |   Lines             |           3405 |           3416 |   +11 |
+ |   Covered           |           1150 |           1161 |   +11 |
+ | Code to Test Ratio  |          1:0.9 |          1:0.9 |  +0.0 |
  |   Code              |           7018 |           7037 |   +19 |
+ |   Test              |           6578 |           6616 |   +38 |
- | Test Execution Time |            12s |            14s |   +2s |

Code coverage of files in pull request scope (79.2% → 79.7%)

Files Coverage +/- Status
md/md.go 79.7% +0.4% modified

Reported by octocov

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request tagpr:minor

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant